
<!DOCTYPE html>

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta charset="utf-8" />
    <title>Overview of Bent Plume Model Module &#8212; Texas A&amp;M Oil spill / Outfall Calculator 2.1.0 documentation</title>
    <link rel="stylesheet" href="../_static/alabaster.css" type="text/css" />
    <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
    <script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
    <script src="../_static/jquery.js"></script>
    <script src="../_static/underscore.js"></script>
    <script src="../_static/doctools.js"></script>
    <script src="../_static/language_data.js"></script>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="bent_plume_model.Model" href="../autodoc/bpm/bent_plume_model.Model.html" />
    <link rel="prev" title="smp.outer_fr" href="../autodoc/spm/smp.outer_fr.html" />
   
  <link rel="stylesheet" href="../_static/custom.css" type="text/css" />
  
  
  <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />

  </head><body>
  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          

          <div class="body" role="main">
            
  <div class="section" id="overview-of-bent-plume-model-module">
<h1>Overview of Bent Plume Model Module<a class="headerlink" href="#overview-of-bent-plume-model-module" title="Permalink to this headline">¶</a></h1>
<dl class="field-list simple">
<dt class="field-odd">Release</dt>
<dd class="field-odd"><p>2.1</p>
</dd>
<dt class="field-even">Date</dt>
<dd class="field-even"><p>Jun 05, 2020</p>
</dd>
</dl>
<span class="target" id="module-bent_plume_model"></span><div class="section" id="bent-plume-model">
<h2>Bent Plume Model<a class="headerlink" href="#bent-plume-model" title="Permalink to this headline">¶</a></h2>
<p>Simulate a buoyant plume in crossflowing ambient conditions</p>
<p>This module defines the classes, methods, and functions necessary to simulate
the buoyant plume behavior in crossflowing ambient conditions, where the
intrusion layer is not expected to interact with the rising stage of the
plume. The ambient water properties are provided through an <cite>ambient.Profile</cite>
class object, which contains a netCDF4-classic dataset of CTD data and the
needed interpolation methods. The <cite>dbm</cite> class objects <cite>dbm.FluidParticle</cite> and
<cite>dbm.InsolubleParticle</cite> report the properties of the dispersed phase during
the simulation, and these methods are provided to the model through the
objects defined in <cite>dispersed_phases</cite>.</p>
<p>This module manages the setup, simulation, and post-processing for the model.
The numerical solution is contained in the <cite>lpm</cite> module.</p>
<div class="section" id="notes">
<h3>Notes<a class="headerlink" href="#notes" title="Permalink to this headline">¶</a></h3>
<p>This model is a Lagrangian plume integral model following the approach in
Lee and Cheung (1990) for single-phase plumes, updated using the shear
entrainment formulation in Jirka (2004), and adapted to multiphase plumes
following the methods of Johansen (2000, 2003) and Zheng and Yapa (1997).
Several modifications are made to make the model consistent with the approach
in Socolofsky et al. (2008) and to match the available validation data.</p>
<p>The model can run as a single-phase or multi-phase plume.  A single-phase
plume simply has an empty <cite>particles</cite> list.</p>
</div>
<div class="section" id="see-also">
<h3>See Also<a class="headerlink" href="#see-also" title="Permalink to this headline">¶</a></h3>
<dl class="simple">
<dt><cite>stratified_plume_model</cite><span class="classifier">Predicts the plume solution for quiescent ambient</span></dt><dd><p>conditions or weak crossflows, where the intrusion (outer plume)
interacts with the upward rising plume in a double-plume integral model
approach.  Such a situation is handeled properly in the
<cite>stratified_plume_model</cite> and would violate the assumption of non-
iteracting Lagrangian plume elements as required in this module.</p>
</dd>
<dt><cite>single_bubble_model</cite><span class="classifier">Tracks the trajectory of a single bubble, drop or</span></dt><dd><p>particle through the water column.  The numerical solution used here,
including the various object types and their functionality, follows the
pattern in the <cite>single_bubble_model</cite>.  The main difference is the more
complex state space and governing equations.</p>
</dd>
</dl>
</div>
</div>
<div class="section" id="class-objects-and-methods">
<h2>Class Objects and Methods<a class="headerlink" href="#class-objects-and-methods" title="Permalink to this headline">¶</a></h2>
<p>The <code class="docutils literal notranslate"><span class="pre">Model</span></code> object is the main interface to the <code class="docutils literal notranslate"><span class="pre">bent_plume_model</span></code>. Its
definition and methods are as follows:</p>
<table class="longtable docutils align-default">
<colgroup>
<col style="width: 10%" />
<col style="width: 90%" />
</colgroup>
<tbody>
<tr class="row-odd"><td><p><a class="reference internal" href="../autodoc/bpm/bent_plume_model.Model.html#bent_plume_model.Model" title="bent_plume_model.Model"><code class="xref py py-obj docutils literal notranslate"><span class="pre">Model</span></code></a>([profile, simfile])</p></td>
<td><p>Master class object for controlling and post-processing the simulation</p></td>
</tr>
<tr class="row-even"><td><p><a class="reference internal" href="../autodoc/bpm/bent_plume_model.Model.simulate.html#bent_plume_model.Model.simulate" title="bent_plume_model.Model.simulate"><code class="xref py py-obj docutils literal notranslate"><span class="pre">Model.simulate</span></code></a>(self, X, D, Vj, phi_0, …[, …])</p></td>
<td><p>Simulate the plume dynamics from given initial conditions</p></td>
</tr>
<tr class="row-odd"><td><p><a class="reference internal" href="../autodoc/bpm/bent_plume_model.Model.save_sim.html#bent_plume_model.Model.save_sim" title="bent_plume_model.Model.save_sim"><code class="xref py py-obj docutils literal notranslate"><span class="pre">Model.save_sim</span></code></a>(self, fname, profile_path, …)</p></td>
<td><p>Save the current simulation results</p></td>
</tr>
<tr class="row-even"><td><p><a class="reference internal" href="../autodoc/bpm/bent_plume_model.Model.save_txt.html#bent_plume_model.Model.save_txt" title="bent_plume_model.Model.save_txt"><code class="xref py py-obj docutils literal notranslate"><span class="pre">Model.save_txt</span></code></a>(self, base_name, …)</p></td>
<td><p>Save the state space in ascii text format for exporting</p></td>
</tr>
<tr class="row-odd"><td><p><a class="reference internal" href="../autodoc/bpm/bent_plume_model.Model.load_sim.html#bent_plume_model.Model.load_sim" title="bent_plume_model.Model.load_sim"><code class="xref py py-obj docutils literal notranslate"><span class="pre">Model.load_sim</span></code></a>(self, fname)</p></td>
<td><p>Load in a saved simulation result file for post-processing</p></td>
</tr>
<tr class="row-even"><td><p><a class="reference internal" href="../autodoc/bpm/bent_plume_model.Model.plot_state_space.html#bent_plume_model.Model.plot_state_space" title="bent_plume_model.Model.plot_state_space"><code class="xref py py-obj docutils literal notranslate"><span class="pre">Model.plot_state_space</span></code></a>(self, fig)</p></td>
<td><p>Plot the simulation state space</p></td>
</tr>
<tr class="row-odd"><td><p><a class="reference internal" href="../autodoc/bpm/bent_plume_model.Model.plot_all_variables.html#bent_plume_model.Model.plot_all_variables" title="bent_plume_model.Model.plot_all_variables"><code class="xref py py-obj docutils literal notranslate"><span class="pre">Model.plot_all_variables</span></code></a>(self, fig)</p></td>
<td><p>Plot a comprehensive suite of simulation results</p></td>
</tr>
</tbody>
</table>
<p>All of the model parameters are contained in the <code class="docutils literal notranslate"><span class="pre">ModelParams</span></code> object. This
object is described in the following:</p>
<table class="longtable docutils align-default">
<colgroup>
<col style="width: 10%" />
<col style="width: 90%" />
</colgroup>
<tbody>
<tr class="row-odd"><td><p><a class="reference internal" href="../autodoc/bpm/bent_plume_model.ModelParams.html#bent_plume_model.ModelParams" title="bent_plume_model.ModelParams"><code class="xref py py-obj docutils literal notranslate"><span class="pre">ModelParams</span></code></a>(profile)</p></td>
<td><p>Fixed model parameters for the bent plume model</p></td>
</tr>
</tbody>
</table>
<p>Because bent plume model particles need to be tracked and can leave the
plume, they require extra capabilities compared to particles in the
<code class="docutils literal notranslate"><span class="pre">dispersed_phases</span></code> module. For this, we define the <code class="docutils literal notranslate"><span class="pre">Particle</span></code> object in
the bent plume model module. It has the following definition and methods:</p>
<table class="longtable docutils align-default">
<colgroup>
<col style="width: 10%" />
<col style="width: 90%" />
</colgroup>
<tbody>
<tr class="row-odd"><td><p><a class="reference internal" href="../autodoc/bpm/bent_plume_model.Particle.html#bent_plume_model.Particle" title="bent_plume_model.Particle"><code class="xref py py-obj docutils literal notranslate"><span class="pre">Particle</span></code></a>(x, y, z, dbm_particle, m0, T0, nb0, …)</p></td>
<td><p>Special model properties for tracking inside a Lagrangian plume object</p></td>
</tr>
<tr class="row-even"><td><p><a class="reference internal" href="../autodoc/bpm/bent_plume_model.Particle.properties.html#bent_plume_model.Particle.properties" title="bent_plume_model.Particle.properties"><code class="xref py py-obj docutils literal notranslate"><span class="pre">Particle.properties</span></code></a>(self, m, T, P, Sa, Ta, t)</p></td>
<td><p>Return the particle properties from the discrete bubble model</p></td>
</tr>
<tr class="row-odd"><td><p><a class="reference internal" href="../autodoc/bpm/bent_plume_model.Particle.diameter.html#bent_plume_model.Particle.diameter" title="bent_plume_model.Particle.diameter"><code class="xref py py-obj docutils literal notranslate"><span class="pre">Particle.diameter</span></code></a>(self, m, T, P, Sa, Ta)</p></td>
<td><p>Compute the diameter of a particle from mass and density</p></td>
</tr>
<tr class="row-even"><td><p><a class="reference internal" href="../autodoc/bpm/bent_plume_model.Particle.biodegradation_rate.html#bent_plume_model.Particle.biodegradation_rate" title="bent_plume_model.Particle.biodegradation_rate"><code class="xref py py-obj docutils literal notranslate"><span class="pre">Particle.biodegradation_rate</span></code></a>(self, t)</p></td>
<td><p>Compute the biodegradation rate constants</p></td>
</tr>
<tr class="row-odd"><td><p><a class="reference internal" href="../autodoc/bpm/bent_plume_model.Particle.update.html#bent_plume_model.Particle.update" title="bent_plume_model.Particle.update"><code class="xref py py-obj docutils literal notranslate"><span class="pre">Particle.update</span></code></a>(self, m, T, P, Sa, Ta, t)</p></td>
<td><p>Store the instantaneous values of the particle properties</p></td>
</tr>
<tr class="row-even"><td><p><a class="reference internal" href="../autodoc/bpm/bent_plume_model.Particle.track.html#bent_plume_model.Particle.track" title="bent_plume_model.Particle.track"><code class="xref py py-obj docutils literal notranslate"><span class="pre">Particle.track</span></code></a>(self, t_p, X_cl, X_p, q_local)</p></td>
<td><p>Track the particle in the Lagragian plume model</p></td>
</tr>
<tr class="row-odd"><td><p><a class="reference internal" href="../autodoc/bpm/bent_plume_model.Particle.outside.html#bent_plume_model.Particle.outside" title="bent_plume_model.Particle.outside"><code class="xref py py-obj docutils literal notranslate"><span class="pre">Particle.outside</span></code></a>(self, Ta, Sa, Pa)</p></td>
<td><p>Remove the effect of particles if they are outside the plume</p></td>
</tr>
<tr class="row-even"><td><p><a class="reference internal" href="../autodoc/bpm/bent_plume_model.Particle.run_sbm.html#bent_plume_model.Particle.run_sbm" title="bent_plume_model.Particle.run_sbm"><code class="xref py py-obj docutils literal notranslate"><span class="pre">Particle.run_sbm</span></code></a>(self, profile)</p></td>
<td><p>Run the <cite>single_bubble_model</cite> to track particles outside the plume</p></td>
</tr>
</tbody>
</table>
<p>Local variables defined for each slice of the plume are stored in a
<code class="docutils literal notranslate"><span class="pre">LagElement</span></code> object. Its definition and methods are as follows:</p>
<table class="longtable docutils align-default">
<colgroup>
<col style="width: 10%" />
<col style="width: 90%" />
</colgroup>
<tbody>
<tr class="row-odd"><td><p><a class="reference internal" href="../autodoc/bpm/bent_plume_model.LagElement.html#bent_plume_model.LagElement" title="bent_plume_model.LagElement"><code class="xref py py-obj docutils literal notranslate"><span class="pre">LagElement</span></code></a>(t0, q0, D, profile, p, particles, …)</p></td>
<td><p>Manages the Lagragian plume element state space and derived variables</p></td>
</tr>
<tr class="row-even"><td><p><a class="reference internal" href="../autodoc/bpm/bent_plume_model.LagElement.update.html#bent_plume_model.LagElement.update" title="bent_plume_model.LagElement.update"><code class="xref py py-obj docutils literal notranslate"><span class="pre">LagElement.update</span></code></a>(self, t, q, profile, p[, …])</p></td>
<td><p>Update the <cite>LagElement</cite> object with the current local conditions</p></td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="module-functions">
<h2>Module Functions<a class="headerlink" href="#module-functions" title="Permalink to this headline">¶</a></h2>
<div class="section" id="utility-functions">
<h3>Utility Functions<a class="headerlink" href="#utility-functions" title="Permalink to this headline">¶</a></h3>
<p>The bent plume model objects defined above use several utilities to perform
their numerical tasks. These are generally not intended to be called directly
by the user and are summarized below:</p>
<table class="longtable docutils align-default">
<colgroup>
<col style="width: 10%" />
<col style="width: 90%" />
</colgroup>
<tbody>
<tr class="row-odd"><td><p><a class="reference internal" href="../autodoc/bpm/bent_plume_model.plot_state_space.html#bent_plume_model.plot_state_space" title="bent_plume_model.plot_state_space"><code class="xref py py-obj docutils literal notranslate"><span class="pre">plot_state_space</span></code></a>(t, q, q_local, profile, p, …)</p></td>
<td><p>Plot the Lagrangian model state space</p></td>
</tr>
<tr class="row-even"><td><p><a class="reference internal" href="../autodoc/bpm/bent_plume_model.plot_all_variables.html#bent_plume_model.plot_all_variables" title="bent_plume_model.plot_all_variables"><code class="xref py py-obj docutils literal notranslate"><span class="pre">plot_all_variables</span></code></a>(t, q, q_local, profile, …)</p></td>
<td><p>Plot a comprehensive suite of simulation results</p></td>
</tr>
<tr class="row-odd"><td><p><a class="reference internal" href="../autodoc/bpm/bent_plume_model.width_projection.html#bent_plume_model.width_projection" title="bent_plume_model.width_projection"><code class="xref py py-obj docutils literal notranslate"><span class="pre">width_projection</span></code></a>(Sx, Sy, b)</p></td>
<td><p>Find the location of the plume width in x, y, z space</p></td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="numerical-model-functions">
<h3>Numerical Model Functions<a class="headerlink" href="#numerical-model-functions" title="Permalink to this headline">¶</a></h3>
<p>The main numerical modeling functions for the bent plume model are stored in
the <code class="docutils literal notranslate"><span class="pre">lmp</span></code> module. These functions could be ported to Fortran or another
language, but are not intended for the user to call directly. Instead, these
are used by the objects defined above. The functions contained in the <code class="docutils literal notranslate"><span class="pre">lmp</span></code>
module are:</p>
<table class="longtable docutils align-default">
<colgroup>
<col style="width: 10%" />
<col style="width: 90%" />
</colgroup>
<tbody>
<tr class="row-odd"><td><p><a class="reference internal" href="../autodoc/bpm/lmp.derivs.html#lmp.derivs" title="lmp.derivs"><code class="xref py py-obj docutils literal notranslate"><span class="pre">derivs</span></code></a>(t, q, q0_local, q1_local, profile, p, …)</p></td>
<td><p>Calculate the derivatives for the system of ODEs for a Lagrangian plume</p></td>
</tr>
<tr class="row-even"><td><p><a class="reference internal" href="../autodoc/bpm/lmp.calculate.html#lmp.calculate" title="lmp.calculate"><code class="xref py py-obj docutils literal notranslate"><span class="pre">calculate</span></code></a>(t0, q0, q0_local, profile, p, …)</p></td>
<td><p>Integrate an the Lagrangian plume solution</p></td>
</tr>
<tr class="row-odd"><td><p><a class="reference internal" href="../autodoc/bpm/lmp.correct_temperature.html#lmp.correct_temperature" title="lmp.correct_temperature"><code class="xref py py-obj docutils literal notranslate"><span class="pre">correct_temperature</span></code></a>(r, particles)</p></td>
<td><p>Make sure the correct temperature is stored in the state space solution</p></td>
</tr>
<tr class="row-even"><td><p><a class="reference internal" href="../autodoc/bpm/lmp.correct_particle_tracking.html#lmp.correct_particle_tracking" title="lmp.correct_particle_tracking"><code class="xref py py-obj docutils literal notranslate"><span class="pre">correct_particle_tracking</span></code></a>(r, particles)</p></td>
<td><p>Remove the particle tracking solution after particles exit plume</p></td>
</tr>
<tr class="row-odd"><td><p><a class="reference internal" href="../autodoc/bpm/lmp.entrainment.html#lmp.entrainment" title="lmp.entrainment"><code class="xref py py-obj docutils literal notranslate"><span class="pre">entrainment</span></code></a>(q0_local, q1_local, p)</p></td>
<td><p>Compute the total shear and forced entrainment at one time step</p></td>
</tr>
<tr class="row-even"><td><p><a class="reference internal" href="../autodoc/bpm/lmp.track_particles.html#lmp.track_particles" title="lmp.track_particles"><code class="xref py py-obj docutils literal notranslate"><span class="pre">track_particles</span></code></a>(q0_local, q1_local, md, …)</p></td>
<td><p>Compute the forcing variables needed to track particles</p></td>
</tr>
<tr class="row-odd"><td><p><a class="reference internal" href="../autodoc/bpm/lmp.local_coords.html#lmp.local_coords" title="lmp.local_coords"><code class="xref py py-obj docutils literal notranslate"><span class="pre">local_coords</span></code></a>(q0_local, q1_local, ds)</p></td>
<td><p>Compute the rotation matrix from (x, y, z) to (l, n, m)</p></td>
</tr>
<tr class="row-even"><td><p><a class="reference internal" href="../autodoc/bpm/lmp.main_ic.html#lmp.main_ic" title="lmp.main_ic"><code class="xref py py-obj docutils literal notranslate"><span class="pre">main_ic</span></code></a>(profile, particles, X, D, Vj, phi_0, …)</p></td>
<td><p>Compute the initial conditions for the Lagrangian plume state space</p></td>
</tr>
<tr class="row-odd"><td><p><a class="reference internal" href="../autodoc/bpm/lmp.bent_plume_ic.html#lmp.bent_plume_ic" title="lmp.bent_plume_ic"><code class="xref py py-obj docutils literal notranslate"><span class="pre">bent_plume_ic</span></code></a>(profile, particles, Qj, A, D, …)</p></td>
<td><p>Build the Lagragian plume state space given the initial conditions</p></td>
</tr>
<tr class="row-even"><td><p><a class="reference internal" href="../autodoc/bpm/lmp.zfe_volume_flux.html#lmp.zfe_volume_flux" title="lmp.zfe_volume_flux"><code class="xref py py-obj docutils literal notranslate"><span class="pre">zfe_volume_flux</span></code></a>(profile, X0, R, Vj, Sj, Tj)</p></td>
<td><p>Compute the volume flux of continous phase discharge fluid at the release</p></td>
</tr>
<tr class="row-odd"><td><p><a class="reference internal" href="../autodoc/bpm/lmp.flux_to_velocity.html#lmp.flux_to_velocity" title="lmp.flux_to_velocity"><code class="xref py py-obj docutils literal notranslate"><span class="pre">flux_to_velocity</span></code></a>(Q, A, phi, theta)</p></td>
<td><p>Convert fluid flow rate to three-component velocity</p></td>
</tr>
</tbody>
</table>
</div>
</div>
</div>


          </div>
          
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
        <div class="sphinxsidebarwrapper">
<h1 class="logo"><a href="../index.html">Texas A&M Oil spill / Outfall Calculator</a></h1>








<h3>Navigation</h3>
<ul class="current">
<li class="toctree-l1 current"><a class="reference internal" href="../user_manual.html">TAMOC User Manual</a></li>
<li class="toctree-l1"><a class="reference internal" href="../unit_tests.html">Unit Tests</a></li>
<li class="toctree-l1"><a class="reference internal" href="../glossary.html">Glossary</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../bugs.html">Reporting Bugs</a></li>
<li class="toctree-l1"><a class="reference internal" href="../readme.html">Read Me File</a></li>
<li class="toctree-l1"><a class="reference internal" href="../release.html">Release Notes</a></li>
<li class="toctree-l1"><a class="reference internal" href="../license.html">License</a></li>
</ul>

<div class="relations">
<h3>Related Topics</h3>
<ul>
  <li><a href="../index.html">Documentation overview</a><ul>
  <li><a href="../user_manual.html">TAMOC User Manual</a><ul>
      <li>Previous: <a href="../autodoc/spm/smp.outer_fr.html" title="previous chapter">smp.outer_fr</a></li>
      <li>Next: <a href="../autodoc/bpm/bent_plume_model.Model.html" title="next chapter">bent_plume_model.Model</a></li>
  </ul></li>
  </ul></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
  <h3 id="searchlabel">Quick search</h3>
    <div class="searchformwrapper">
    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" />
      <input type="submit" value="Go" />
    </form>
    </div>
</div>
<script>$('#searchbox').show(0);</script>








        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="footer">
      &copy;2020, Scott A. Socolofsky.
      
      |
      Powered by <a href="http://sphinx-doc.org/">Sphinx 2.4.4</a>
      &amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
      
      |
      <a href="../_sources/modules/bpm.rst.txt"
          rel="nofollow">Page source</a>
    </div>

    

    
  </body>
</html>